Theme an app

Browse the sample

.NET Multi-platform App UI (.NET MAUI) apps can respond to style changes dynamically at runtime by using the DynamicResource markup extension. This markup extension is similar to the StaticResource markup extension, in that both use a dictionary key to fetch a value from a ResourceDictionary. However, while the StaticResource markup extension performs a single dictionary lookup, the DynamicResource markup extension maintains a link to the dictionary key. Therefore, if the value associated with the key is replaced, the change is applied to the VisualElement. This enables runtime theming to be implemented in .NET MAUI apps.

The process for implementing runtime theming in a .NET MAUI app is as follows:

Important

Use the StaticResource markup extension if you don't need to change the app theme at runtime.

The following screenshot shows themed pages, with the iOS app using a light theme and the Android app using a dark theme:

Note

Changing a theme at runtime requires the use of XAML styles, and is not possible using CSS.

.NET MAUI also has the ability to respond to system theme changes. The system theme may change for a variety of reasons, depending on the device configuration. This includes the system theme being explicitly changed by the user, it changing due to the time of day, and it changing due to environmental factors such as low light. For more information, see Respond to system theme changes.

A theme is defined as a collection of resource objects stored in a ResourceDictionary.

The following example shows a ResourceDictionary for a light theme named LightTheme:

The following example shows a ResourceDictionary for a dark theme named DarkTheme:

Each ResourceDictionary contains Color resources that define their respective themes, with each ResourceDictionary using identical key values. For more information about resource dictionaries, see Resource Dictionaries.

Important

A code behind file is required for each ResourceDictionary, which calls the InitializeComponent method. This is necessary so that a CLR object representing the chosen theme can be created at runtime.

An app requires a default theme, so that controls have values for the resources they consume. A default theme can be set by merging the theme's ResourceDictionary into the app-level ResourceDictionary that's defined in App.xaml:

For more information about merging resource dictionaries, see Merged resource dictionaries.

When an app wants to consume a resource that's stored in a ResourceDictionary that represents a theme, it should do so with the DynamicResource markup extension. This ensures that if a different theme is selected at runtime, the values from the new theme will be applied.

The following example shows three styles from that can be applied to all Label objects in app:

These styles are defined in the app-level resource dictionary, so that they can be consumed by multiple pages. Each style consumes theme resources with the DynamicResource markup extension.

These styles are then consumed by pages:

When a theme resource is consumed directly, it should be consumed with the DynamicResource markup extension. However, when a style that uses the DynamicResource markup extension is consumed, it should be consumed with the StaticResource markup extension.

For more information about styling, see Style apps using XAML. For more information about the DynamicResource markup extension, see Dynamic styles.

When a theme is selected at runtime, an app should:

Any VisualElement objects that set properties with the DynamicResource markup extension will then apply the new theme values. This occurs because the DynamicResource markup extension maintains a link to dictionary keys. Therefore, when the values associated with keys are replaced, the changes are applied to the VisualElement objects.

In the sample application, a theme is selected via a modal page that contains a Picker. The following code shows the OnPickerSelectionChanged method, which is executed when the selected theme changes:

The following example shows removing the current theme and loading a new theme: